@DATABASE "ARx_Func.ag" @VER 1.0a @INDEX ARx_Index/MAIN @NODE MAIN "ARexxGuide | Functions Reference |" @TOC ARexxGuide.guide/MAIN @PREV ARx_Instr.ag/MAIN @NEXT ARx_Operator.ag/MAIN @{FG HIGHLIGHT}AN AMIGAGUIDE TO ARexx@{FG TEXT} Edition: 1.0a by Robin Evans @{" About this section " link ABOUT} ARexx functions: @{" Comparison functions " link CMPRLIST} FIND(), POS(), ABBREV(), etc. @{" String manipulation " link STRLIST} LEFT(), SUBSTR(), etc. @{" Word manipulation " link ARx_Func2.ag/WORDLIST} WORD(), DELWORD(), etc. @{" Char/Num translation " link ARx_Func2.ag/TRANLIST} C2D(), X2C(), D2X() etc. @{" Number manipulation " link ARx_Func2.ag/NUMLIST} RANDOM(), MAX(), etc. @{" Informational " link ARx_Func2.ag/INFOLIST} DATE(), SHOW(), etc. @{" File input/output " link ARx_Func3.ag/FILEIOLIST} OPEN(), READLN(), SEEK(), etc. @{" File management " link ARx_Func3.ag/FILEMGTLIST} DELETE(), EXISTS(), RENAME(), etc. @{" ARexx control " link ARx_Func3.ag/ARXLIST} ADDLIB(), PRAGMA(), etc. @{" Message ports " link ARx_Func4.ag/PORTLIST} OPENPORT(), WAITPKT(), GETARG(), etc. @{" Memory management " link ARx_Func4.ag/MEMLIST} IMPORT(), NEXT(), NULL(), etc. @{" Bit-wise operations " link ARx_Func4.ag/BITLIST} BITAND(), BITCMP(), etc. @{" All functions [INDEX ] " link FUNCLIST} Copyright 1993, Robin Evans. All rights reserved. This guide is @{" shareware " link ArexxGuide.guide/REG}. If you find it useful, please register. @EndNode @Node ABOUT "ARexxGuide | Functions Reference | ABOUT" @PREV MAIN @{FG HIGHLIGHT}REFERENCE TO BUILT-IN AND REXXSUPPORT.LIBRARY FUNCTIONS@{FG TEXT} ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ This section presents a reference to @{" built-in functions " link ARx_Elements3.ag/BLTFUNC} and to the functions included in @{" rexxsupport.library " link RXSPTLIB}. Each node begins with a template that shows the format of the arguments accepted by the function. The following conventions are used: <> A word or term surrounded by angle brackets should be replaced by an expression. Any form of expression that returns a value of the proper type may be used in place of this item. The replacement is often a @{" variable " link ARx_Elements2.ag/VARIABLE}, but it could also be a literal value, an @{" operation " link ARx_Elements3.ag/OPERATION}, or another function @{" call " link ARx_Instr.ag/CALL}. The names used for the items in each template are included as mnemonic devices -- terms that may help the user remember what each expression stands for. They are not otherwise significant. Each term is explained in more detail in the note following the template. [] Items enclosed in square brackets are optional. They may be excluded when the function is called, but the commas that separate optional items are significant. If only the second of two optional items is included, a comma must still be used as a placeholder for the omitted item as it is in the following: SHOW('P',,'0a'x) {} Items enclosed in curly braces and entered in uppercase are literal values. The expression used for such an argument must return one of the values from the list. | A bar is used to separate a list of literal values within {} braces. UPPERCASE characters are used to indicate literal values that may be used as argument. The value may be entered in upper or lowercase when the instruction is actually used. Only the first letter of the option need be included. The value may be entered as any type of @{" expression " link ARx_Elements2.ag/EXPRESSION}. >>> Three angle-braces are used in examples to indicate what the example would output if run from a shell. Those braces and the following text is not part of the code and should not be entered if the example is used. Next: REXXSUPPORT.LIBRARY | Prev: Function ref. | Contents: Function ref. @EndNode @Node RXSPTLIB "ARexxGuide | Functions Reference | REXXSUPPORT.LIBRARY" @NEXT MAIN @{" Functions " link ARx_Elements3.ag/FUNCTION} can be added to ARexx by means of @{" external libraries " link ARx_Elements3.ag/EXTFUNC}. One such library is included with the distribution of ARexx. Called 'rexxsupport.library', it should be present in the user's libs: directory after ARexx is installed. The library adds several Amiga-specific functions that are not defined as a standard part of the REXX language. Included are memory-control functions like @{" ALLOCMEM() " link ARx_Func4.ag/ALLOCMEM()}, file system functions like @{" MAKEDIR() " link ARx_Func3.ag/MAKEDIR()}, and interprocess-communication functions like @{" OPENPORT() " link ARx_Func4.ag/OPENPORT()}. The functions in rexxsupport.library will not automatically be available to ARexx scripts, however. The are available only if the library is explicitly added to the list of libraries through which ARexx searches to find functions. That can be done with the @{" ADDLIB() " link ARx_Func3.ag/ADDLIB()} function or with the @{" RXLIB " link ARx_Cmd.ag/RXLIB} command utility. Examples of loading the library are included with the description of each of those methods. Frequent users of ARexx may wish to add rexxsupport.library to the system during the startup sequence. Next: Function ref. | Prev: About section | Contents: Function ref. @EndNode @Node FuncList "ARexxGuide | Functions reference | INDEX to built-in & support functions"" @Next MAIN @PREV MAIN @{" ABBREV " link ABBREV()} @{" ABS " link ARx_Func2.ag/ABS()} @{" ADDRESS " link ARx_Func3.ag/ADDRESS()} @{" ADDLIB " link ARx_Func3.ag/ADDLIB()} @{" ALLOCMEM " link ARx_Func4.ag/ALLOCMEM()} @{" ARG " link ARx_Func3.ag/ARG()} @{" BADDR " link ARx_Func4.ag/BADDR()} @{" B2C " link ARx_Func2.ag/B2C()} @{" BITAND " link ARx_Func4.ag/BITAND()} @{" BITCHG " link ARx_Func4.ag/BITCHG()} @{" BITCLR " link ARx_Func4.ag/BITCLR()} @{" BITCOMP " link ARx_Func4.ag/BITCOMP()} @{" BITOR " link ARx_Func4.ag/BITOR()} @{" BITSET " link ARx_Func4.ag/BITSET()} @{" BITTST " link ARx_Func4.ag/BITTST()} @{" BITXOR " link ARx_Func4.ag/BITXOR()} @{" C2B " link ARx_Func2.ag/C2B()} @{" C2D " link ARx_Func2.ag/C2D()} @{" C2X " link ARx_Func2.ag/C2X()} @{" CENTER " link CENTER()} @{" CLOSE " link ARx_Func3.ag/CLOSE()} @{" CLOSEPORT " link ARx_Func4.ag/CLOSEPORT()} @{" COMPARE " link COMPARE()} @{" COMPRESS " link COMPRESS()} @{" COPIES " link COPIES()} @{" D2C " link ARx_Func2.ag/D2C()} @{" DATATYPE " link ARx_Func3.ag/DATATYPE()} @{" DATE " link ARx_Func2.ag/DATE()} @{" DELAY " link ARx_Func3.ag/DELAY()} @{" DELETE " link ARx_Func3.ag/DELETE()} @{" DELSTR " link DELSTR()} @{" DELWORD " link ARx_Func2.ag/DELWORD()} @{" DIGITS " link ARx_Func3.ag/DIGITS()} @{" EOF " link ARx_Func3.ag/EOF()} @{" ERRORTEXT " link ARx_Func3.ag/ERRORTEXT()} @{" EXISTS " link ARx_Func3.ag/EXISTS()} @{" EXPORT " link ARx_Func4.ag/EXPORT()} @{" FIND " link FIND()} @{" FORBID " link ARx_Func4.ag/FORBID()} @{" FORM " link ARx_Func3.ag/FORM()} @{" FREEMEM " link ARx_Func4.ag/FREEMEM()} @{" FREESPACE " link ARx_Func4.ag/FREESPACE()} @{" FUZZ " link ARx_Func3.ag/FUZZ()} @{" GETARG " link ARx_Func4.ag/GETARG()} @{" GETCLIP " link ARx_Func3.ag/GETCLIP()} @{" GETPKT " link ARx_Func4.ag/GETPKT()} @{" GETSPACE " link ARx_Func4.ag/GETSPACE()} @{" HASH " link ARx_Func2.ag/HASH()} @{" IMPORT " link ARx_Func4.ag/IMPORT()} @{" INDEX " link INDEX()} @{" INSERT " link INSERT()} @{" LASTPOS " link LASTPOS()} @{" LEFT " link LEFT()} @{" LENGTH " link LENGTH()} @{" LINES " link ARx_Func3.ag/LINES()} @{" MAKEDIR " link ARx_Func3.ag/MAKEDIR()} @{" MAX " link ARx_Func2.ag/MAX()} @{" MIN " link ARx_Func2.ag/MIN()} @{" NEXT " link ARx_Func4.ag/NEXT()} @{" NULL " link ARx_Func4.ag/NULL()} @{" OFFSET " link ARx_Func4.ag/OFFSET()} @{" OPEN " link ARx_Func3.ag/OPEN()} @{" OPENPORT " link ARx_Func4.ag/OPENPORT()} @{" OVERLAY " link OVERLAY()} @{" PERMIT " link ARx_Func4.ag/PERMIT()} @{" POS " link POS()} @{" PRAGMA " link ARx_Func3.ag/PRAGMA()} @{" RANDOM " link ARx_Func2.ag/RANDOM()} @{" RANDU " link ARx_Func2.ag/RANDU()} @{" READCH " link ARx_Func3.ag/READCH()} @{" READLN " link ARx_Func3.ag/READLN()} @{" REMLIB " link ARx_Func3.ag/REMLIB()} @{" RENAME " link ARx_Func3.ag/RENAME()} @{" REPLY " link ARx_Func4.ag/REPLY()} @{" REVERSE " link REVERSE()} @{" RIGHT " link RIGHT()} @{" SEEK " link ARx_Func3.ag/SEEK()} @{" SETCLIP " link ARx_Func3.ag/SETCLIP()} @{" SHOW " link ARx_Func2.ag/SHOW()} @{" SHOWDIR " link ARx_Func2.ag/SHOWDIR()} @{" SHOWLIST " link ARx_Func2.ag/SHOWLIST()} @{" SIGN " link ARx_Func2.ag/SIGN()} @{" SOURCELINE " link ARx_Func3.ag/SOURCELINE()} @{" SPACE " link ARx_Func2.ag/SPACE()} @{" STATEF " link ARx_Func3.ag/STATEF()} @{" STORAGE " link ARx_Func4.ag/STORAGE()} @{" STRIP " link STRIP()} @{" SUBSTR " link SUBSTR()} @{" SUBWORD " link ARx_Func2.ag/SUBWORD()} @{" SYMBOL " link ARx_Func3.ag/SYMBOL()} @{" TIME " link ARx_Func2.ag/TIME()} @{" TRACE " link ARx_Func3.ag/TRACE()} @{" TRANSLATE " link TRANSLATE()} @{" TRIM " link TRIM()} @{" TRUNC " link ARx_Func2.ag/TRUNC()} @{" TYPEPKT " link ARx_Func4.ag/TYPEPKT()} @{" UPPER " link UPPER()} @{" VALUE " link ARx_Func3.ag/VALUE()} @{" VERIFY " link VERIFY()} @{" WAITPKT " link ARx_Func4.ag/WAITPKT()} @{" WORD " link ARx_Func2.ag/WORD()} @{" WORDINDEX " link ARx_Func2.ag/WORDINDEX()} @{" WORDLENGTH " link ARx_Func2.ag/WORDLENGTH()} @{" WORDS " link ARx_Func2.ag/WORDS()} @{" WRITECH " link ARx_Func3.ag/WRITECH()} @{" WRITELN " link ARx_Func3.ag/WRITELN()} @{" X2C " link ARx_Func2.ag/X2C()} @{" XRANGE " link XRANGE()} @EndNode @Node CMPRLIST "ARexxGuide | Functions reference (1 of 12) | COMPARISON" @Prev MAIN @NEXT STRLIST @{" ABBREV " link ABBREV()}(,,[]) @{" COMPARE " link COMPARE()}(,,[]) @{" FIND " link FIND()}(, ) @{" INDEX " link INDEX()}(,, []) @{" LASTPOS " link LASTPOS()}(,,[]) @{" POS " link POS()}(,,[]) @{" VERIFY " link VERIFY()}(, , [{'NOMATCH'|'MATCH'}], []) Related functions: @{" BITCOMP " link ARx_Func4.ag/BITCOMP()} @{" BITTST " link ARx_Func4.ag/BITTST()} @{" DATATYPE " link ARx_Func3.ag/DATATYPE()} Also see @{" Bit manipulation functions " link ARx_Func4.ag/BITLIST} Comparisons of one type or another are one of the most frequent tasks of any program. Comparisons allow a program to branch off to different code based on different conditions. @{" Comparison operators " link ARx_Operator.ag/COMPARISON} give ARexx the standard tools for matching strings, but these functions extend the power of the operators, allowing quick checks for a substring (what @{" Cowlishaw " link ARx_Intro.ag/REF} so elegantly calls a 'needle') in a string (the 'haystack'), or for a word of phrase within a string of words. Next: String functions | Prev: BITXOR() | Contents: Function reference @EndNode @Node ABBREV() "ARexxGuide | Functions reference | Comparison (1 of 7) | ABBREV" @TOC CMPRLIST @Prev CMPRLIST ABBREV(,,[]) returns boolean value Returns 1 if is equal to the leading characters of . If is specified, then must also be at least that long. The comparison is case-sensitive. If is not specified, an empty string will always match . Returns 0 if either condition is not met. Examples: say abbrev('Waldorf','Waldo'); >>> 1 say abbrev('Waldorf','WALDO'); >>> 0 say abbrev(@{" upper('Waldorf') "link UPPER()}, 'WALDO'); >>> 1 Also see @{ " COMPARE " link COMPARE()} @{ " LEFT " link LEFT()} Next: COMPARE() | Prev: Comparison func. | Contents: Comparison func. @EndNode @Node COMPARE() "ARexxGuide | Functions reference | Comparison (2 of 7) | COMPARE" @TOC CMPRLIST COMPARE(,,[]) returns a number The result is 0 if both strings are identical. If they aren't, the number returned is the position of the first character where the strings differ. The shorter string is padded with before the comparison. The default pad character is a blank. Examples: say compare('The first','The only'); >>> 5 say compare('worldwide','wordwide'); >>> 4 say compare('foo','f'); >>> 2 say compare('foo','f','o'); >>> 0 Also see @{ " ABBREV " link ABBREV()} @{ " VERIFY " link VERIFY()} Next: FIND() | Prev: ABBREV() | Contents: Comparison functions @EndNode @Node FIND() "ARexxGuide | Functions reference | Comparison (3 of 7) | FIND" @TOC CMPRLIST FIND(, ) returns a number Locates the blank-delimited word or words within the string and returns the word position of the first match, or 0 if there is no match. The search is case sensitive. Examples: say find('Tied to Godot?','dot'); >>> 0 say find('Tied to Godot?','to'); >>> 2 Also see @{ " INDEX " link INDEX()} @{ " POS " link POS()} @{ " WORDINDEX " link ARx_Func2.ag/WORDINDEX()} In some implementations of REXX, this function is called WORDPOS() and takes arguments in the reverse order. Next: INDEX() | Prev: COMPARE() | Contents: Comparison functions @EndNode @Node INDEX() "ARexxGuide | Functions reference | Comparison (4 of 7) | INDEX" @TOC CMPRLIST INDEX(,, []) returns a number The result is the character position within the string of the the first occurrence of the string or 0 if a match isn't found. If is specified, then the search proceeds from that position in . The search is case sensitive. Examples: say index('Tied to Godot?','dot'); >>> 11 say index('Tied to Godot?','to'); >>> 6 Also see @{ " FIND " link FIND()} @{ " POS " link POS()} Next: LASTPOS() | Prev: FIND() | Contents: Comparison functions @EndNode @Node LASTPOS() "ARexxGuide | Functions reference | Comparison (5 of 7) | LASTPOS" @TOC CMPRLIST LASTPOS(,,[]) returns a number The result is the character position within the string of the the last occurrence of the string or 0 if a match isn't found. If is specified, then the search proceeds backwards from that position in . Examples: say lastpos('eak','growing weaker and weaker'); >>> 21 say lastpos('eak','growing weaker and weaker',20); >>> 10 Also see @{ " POS " link POS()} @{" NOTE: Extracting file names " alink ARx_Notes.ag/FILENAME} Next: POS() | Prev: INDEX() | Contents: Comparison functions @EndNode @Node POS() "ARexxGuide | Functions reference | Comparison (6 of 7) | POS" @TOC CMPRLIST POS(,,[]) returns a number The result is the character position within the string of the the first occurrence of the string or 0 if a match isn't found. If is specified, then the search proceeds forward from that position in . The search is case sensitive. Examples: say pos('eak','growing weaker and weaker') >>> 10 say pos('eak','growing weaker and weaker',11) >>> 21 Also see @{ " LASTPOS " link LASTPOS()} @{ " VERIFY " link VERIFY()} Next: VERIFY() | Prev: LASTPOS() | Contents: Comparison functions @EndNode @Node VERIFY() "ARexxGuide | Functions reference | Comparison (7 of 7) | VERIFY" @TOC CMPRLIST @Next CMPRLIST VERIFY(, , ['MATCH'], []) returns a number Checks for the presence in of any characters that appear in -- a list of characters which may be entered in any order. If the 'MATCH' option is omitted, the functions returns 0 when all characters in are contained in . Otherwise, the number returned is the position of the first character in that does not match a character in . The 'M' (match) option will cause the function to return the position of the first character in that matches a character in . It returns 0 if none of the characters in match a character in . It can be used to verify that invalid characters are not used in or to check for the position of the first of a range of characters. If is specified, the search will begin at that character position in . Examples: say verify('#789-ABD', '1234567890ABCD-#') >>> 0 say verify('#432-cfo', '1234567890ABCD-#') >>> 6 say verify('FileName', ':;*/?`#%', 'm') >>> 0 say verify('File*NAME', ':;*/?`#%', 'm') >>> 5 say verify('File*NAME', ':;*/?`#%', 'm',6) >>> 0 say verify('t:foo/file', ':/', 'm') >>> 2 Also see @{ " DATATYPE " link ARx_Func3.ag/DATATYPE()} @{ " POS " link POS()} @{" NOTE: Checking unique datatypes " alink ARx_Notes.ag/VERIFYNOTE} Next: Comparison functions | Prev: POS() | Contents: Comparison functions @EndNode @Node STRLIST "ARexxGuide | Functions reference (2 of 12) | STRING MANIPULATION" @PREV CMPRLIST @NEXT ARx_Func2.ag/WORDLIST @{" CENTER " link CENTER()}(,,[]) @{" COMPRESS " link COMPRESS()}(, []) @{" COPIES " link COPIES()}(,) @{" DELSTR " link DELSTR()}(,, []) @{" INSERT " link INSERT()}(, ,, [],[]) @{" LEFT " link LEFT()}(,,[]) @{" LENGTH " link LENGTH()}() @{" OVERLAY " link OVERLAY()}(, ,[], [],[]) @{" REVERSE " link REVERSE()}() @{" RIGHT " link RIGHT()}(,,[]) @{" STRIP " link STRIP()}(, [{'B'|'L'|'T'}], []) @{" SUBSTR " link SUBSTR()}(, , [],[]) @{" TRANSLATE " link TRANSLATE()}(,[], [],[]) @{" TRIM " link TRIM()}() @{" UPPER " link UPPER()}() @{" XRANGE " link XRANGE()}([, []) Also see @{" Word manipulation functions " link ARx_Func2.ag/WORDLIST} @{" Number manipulation functions" link ARx_Func2.ag/NUMLIST} @{" PARSE instruction " link ARx_Instr2.ag/PARSE} Nearly any change one might contemplate for a string can be made with one, or a combination of these functions, or one of the closely-allied @{" word manipulation functions " link ARx_Func2.ag/WORDLIST}. They'll cut chunks out of a string -- LEFT(), RIGHT(), SUBSTR(), DELSTR(); or remove only certain characters -- STRIP(), TRIM(), COMPRESS(); or add to the string -- OVERLAY(), INSERT(), COPIES(), CENTER(); or transform it in subtle and wonderful ways -- TRANSLATE(), REVERSE(). Next: Word functions | Prev: FuncList | Contents: Function reference @EndNode @Node CENTER() "ARexxGuide | Functions reference | String (1 of 15) | CENTER" @TOC STRLIST @PREV STRLIST CENTER(,,[]) returns a string The result is a string of characters with centered in it. The is used to fill out the left and right sides of the string. The default pad character is a blank. Example: say '['center('Title',20)']'; >>> [ Title ] say center('Title',22,'*'); >>> ********Title********* Also see @{ " SPACE " link ARx_Func2.ag/SPACE()} @{ " COPIES " link COPIES()} Next: COMPRESS() | Prev: String functions | Contents: String functions @EndNode @Node COMPRESS() "ARexxGuide | Functions reference | String (2 of 15) | COMPRESS" @TOC STRLIST COMPRESS(, []) returns a string Removes any of the characters contained in from . The default character for is a blank, so this function will remove all blanks if only is specified. Examples: say compress('$1,045','$,%'); >>> 1045 say compress('Call me Ismael.'); >>> CallmeIsmael. Also see @{ " TRANSLATE " link TRANSLATE()} @{ " STRIP " link STRIP()} @{ " SPACE " link ARx_Func2.ag/SPACE()} @{" NOTE: Counting characters with COMPRESS() " alink ARx_Notes.ag/COUNTCHAR} Next: COPIES() | Prev: CENTER() | Contents: String functions @EndNode @Node COPIES() "ARexxGuide | Functions reference | String (3 of 15) | COPIES" @TOC STRLIST COPIES(,) returns a string The result is a new string composed of concatenated with itself times. Example: say copies('xo',6); >>> xoxoxoxoxoxo Also see @{ " XRANGE " link XRANGE()} @{ " CENTER " link CENTER()} Next: DELSTR() | Prev: COMPRESS() | Contents: String functions @EndNode @Node DELSTR() "ARexxGuide | Functions reference | String (4 of 15) | DELSTR" @TOC STRLIST DELSTR(,, []) returns a string Deletes a portion of of characters beginning at the character position. The new string is returned. If is greater than the length of then is returned unchanged. If is omitted, all characters beginning at position are deleted. Example: say delstr('indifference',3,3); >>> inference Also see @{ " DELWORD " link ARx_Func2.ag/DELWORD()} @{ " RIGHT " link RIGHT()} @{ " SUBSTR " link SUBSTR()} @{ " INSERT " link INSERT()} @{ " OVERLAY " link OVERLAY()} Next: INSERT() | Prev: COPIES() | Contents: String functions @EndNode @Node INSERT() "ARexxGuide | Functions reference | String (5 of 15) | INSERT" @TOC STRLIST INSERT(, ,, [],[]) returns a string is inserted into beginning at , the character-count position. will be padded with or truncated to characters. If is greater than the length of then will be added to the end of before the new string is added. If is 0, then will be padded to and then added to the start of The default length is the length of . The default pad character is a blank. Example: say insert('always behaved like','I have a pig.',7,20) >>> I have always behaved like a pig. Also see @{ " OVERLAY " link OVERLAY()} @{ " DELSTR " link DELSTR()} Next: LEFT() | Prev: DELSTR() | Contents: String functions @EndNode @Node LEFT() "ARexxGuide | Functions reference | String (6 of 15) | LEFT" @TOC STRLIST LEFT(,,[]) returns a string The result is a string of characters made up of the leftmost characters in . If is greater than the length of , then the string returned is filled out on the right with -- a quick way to left-justify a string. The default pad character is a blank. Example: say left('never to stop saying',13); >>> never to stop say left('Widget', 12)'|' >>> Widget | say left('No', 4, '!') >>> No!! Also see @{ " RIGHT " link RIGHT()} @{ " SUBSTR " link SUBSTR()} @{ " ABBREV " link ABBREV()} @{" NOTE: Formatting tables " alink ARx_Notes.ag/FORMATNOTE} Next: LENGTH() | Prev: INSERT() | Contents: String functions @EndNode @Node LENGTH() "ARexxGuide | Functions reference | String (7 of 15) | LENGTH" @TOC STRLIST LENGTH() returns a number The result is the number of characters in . Example: say length('never to stop saying'); >>> 20 @{" NOTE: Counting characters with COMPRESS() " alink ARx_Notes.ag/COUNTCHAR} Next: OVERLAY() | Prev: LEFT() | Contents: String functions @EndNode @Node OVERLAY() "ARexxGuide | Functions reference | String (8 of 15) | OVERLAY" @TOC STRLIST OVERLAY(, ,[], [],[]) returns a string Replaces the characters of starting at position with the characters of . The default starting position is the beginning of . If is not specified, all of the characters from will be overlaid on . If a is specified, then will either be truncated to that length or expanded to using to fill out the string. The default pad character is a blank. Examples: say overlay('12', 'abcdefg', 3, 4, '*') >>> ab12**g say overlay('abc', '12345678', 4, 2) >>> 123ab678 say overlay( 'think of it',, 'the less I concentrate the more certain I am', 12) >>> the less I think of it the more certain I am Also see @{ " INSERT " link INSERT()} @{ " DELSTR " link DELSTR()} Note that the third example above uses the comma @{" continuation character " link ARx_Elements.ag/COMMA} to turn two lines of text into one program line. Next: REVERSE() | Prev: LENGTH() | Contents: String functions @EndNode @Node REVERSE() "ARexxGuide | Functions reference | String (9 of 15) | REVERSE" @TOC STRLIST REVERSE() returns a string The result is flipped end for end. Example: say reverse('chameleon'); >>> noelemahc Also see @{ " LASTPOS " link LASTPOS()} Next: RIGHT() | Prev: OVERLAY() | Contents: String functions @EndNode @Node RIGHT() "ARexxGuide | Functions reference | String (10 of 15) | RIGHT" @TOC STRLIST RIGHT(,,[]) returns a string The result is a string of characters made up the rightmost characters in . If is greater than the length of , then the result is filled out on the left with -- a quick way to right-justify a string. The default pad character is a blank. Example: say right('never to stop saying',11); >>> stop saying say '$'right(4.50, 6) >>> $ 4.50 say '$'right(123.99, 6) >>> $123.99 say right('Whoa', 6, 'W') >>> WWWhoa Also see @{ " LEFT " link LEFT()} @{ " SUBSTR " link SUBSTR()} @{ " DELSTR " link DELSTR()} @{" NOTE: Formatting tables " alink ARx_Notes.ag/FORMATNOTE} Next: STRIP() | Prev: REVERSE() | Contents: String functions @EndNode @Node STRIP() "ARexxGuide | Functions reference | String (11 of 15) | STRIP" @TOC STRLIST STRIP(, [{'B'|'L'|'T'}], []) returns a string Removes spaces (by default) or any character in from the leading, trailing, or both ends (specified by the option used as the second argument) of . The default option is 'B'. Example: say '|'strip(' understand ')'|'; >>> |understand| say '|'strip(' understand ',L)'|'; >>> |understand | say '|'strip('___understand___',T,'_')'|'; >>> |___understand| say strip('understand',,'dnu') >>> ersta Also see @{ " COMPRESS " link COMPRESS()} @{ " TRIM " link TRIM()} The examples above use the abuttal @{" concatenation operator " link ARx_Operator.ag/CONCATENATION} to add the character '|' to the beginning and end of the string returned by STRIP(). Next: SUBSTR() | Prev: RIGHT() | Contents: String functions @EndNode @Node SUBSTR() "ARexxGuide | Functions reference | String (12 of 15) | SUBSTR" @TOC STRLIST SUBSTR(, , [],[]) returns a string The result is a string of characters made up the characters in beginning at . If is not specified, then all of the string to the right of will be returned. If the argument is specified, the returned string will have characters, filled out, if necessary, with . The default pad character is a blank. Example: say substr('indifference',3,3); >>> dif say substr('No way',4,5,'!') >>> way!! Also see @{ " LEFT " link LEFT()} @{ " RIGHT " link RIGHT()} @{ " DELSTR " link DELSTR()} @{ " SUBWORD " link ARx_Func2.ag/SUBWORD()} @{ " TRUNC " link ARx_Func2.ag/TRUNC()} Next: TRANSLATE() | Prev: STRIP() | Contents: String functions @EndNode @Node TRANSLATE() "ARexxGuide | Functions reference | String (13 of 15) | TRANSLATE" @TOC STRLIST TRANSLATE(,[], [],[]) returns a string Any character in that also appears in the is converted to the corresponding character in the or to the if there isn't a corresponding character in the . If neither table is supplied, then the is converted to upper case, just as it would be by @{" UPPER() " link UPPER()}. The default pad character is a blank. Examples: say translate('abcdef', '123456', 'abcdef') >>> 123456 say translate('abcdef', '123456', 'defabc') >>> 456123 say translate('abcdef', '1234', 'defabc','*') >>> 4**123 say translate('UNNAMABLE', xrange('a','z'), xrange('A','Z')) >>> unnamable Also see @{ " COMPRESS " link COMPRESS()} Next: TRIM() | Prev: SUBSTR() | Contents: String functions @EndNode @Node TRIM() "ARexxGuide | Functions reference | String (14 of 15) | TRIM" @TOC STRLIST TRIM() returns a string The result is with the trailing blanks removed. Example: say '|'trim(' understand ')'|'; >>> | understand| Also see @{ " STRIP " link STRIP()} Next: UPPER() | Prev: TRANSLATE() | Contents: String functions @EndNode @Node UPPER() "ARexxGuide | Functions reference | String (15 of 15) | UPPER" @TOC STRLIST UPPER() returns a string The result is translated to all uppercase characters. Example: say upper('Waldorf') >>> WALDORF Also see @{ " TRANSLATE " link TRANSLATE()} ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ A can be translated to lowercase with the following function: TRANSLATE(, xrange('a', 'z'), xrange('A','Z')) The function @{" BITOR() " link ARx_Func4.ag/BITOR()} will also translate the alphabetic characters in to lowercase characters, but it will shift the ASCII characters between 91 and 95 { [ \ ] ^ _} to characters 123 through Next: String functions | Prev: XRANGE() | Contents: String functions @EndNode @Node XRANGE() "ARexxGuide | Functions reference | Number (9 of 9) | XRANGE" @TOC STRLIST @NEXT STRLIST XRANGE([, []) returns a string The result is a string comprised of all the characters between and including and . The output of the function is a character string. Use the @{" c2x() " link ARx_Func2.ag/C2X()} function, for example, to convert the output to hexadecimal number format. Examples: say xrange('a','g'); >>> abcdefg say xrange(1,8); >>> 12345678 say c2x(xrange('c'x,'14'x)); >>> 0C0D0E0F1011121314 Also see @{ " COPIES " link COPIES()} Next: String functions | Prev: UPPER() | Contents: String functions @EndNode